getReplacementSongs

Returns a list of songs to potentially be scheduled at a specified time that test well against the rules defined in MusicMaster. This is one of the most popular API commands third party systems use because it allows your system to tap into the scheduling intelligence of MusicMaster. Replacement songs follow the rules set up within MusicMaster ensuring format and overall sound are maintained when the song is changed.

 

This function was originally designed to replace already scheduled songs and to fill in simple element types (Fixed and Manual only). There are some conditions to keep in mind:

 

  • If the element is already scheduled, it will use the category of the scheduled song.

  • If it is an unscheduled Fixed or Manual element, then it will use the category designated in the element properties.

  • If the caller uses the optional Query tag to designate different categories and/or search filters, then this completely overrides the element properties or scheduled song category and can work on any type of element. Without the query tag being used, other unscheduled element types besides Fixed and Manual will report an error.

  • If you call this function for an element that already has a song scheduled, the song that is already scheduled will not be included in the results. Only alternative replacement songs are returned.

Sample Request

<mmRequest command="getReplacementSongs" station="ID" [version="1"] [client=""] [userData=""]>
	<contents>
		<element airTime="yyyy-mm-ddThh:nn:ss" [pos="before|after|replace"] [songId="x"] [cutId="x"] [historyId="x"] />
		[<testFilter>perfectOnly|breakable</testFilter>]
		[<maxSongs>10</maxSongs>]
		[<goalSort>1</goalSort>]
		[<query>
			[<categories>
				<category [id="1"] [code="A"]/>
			</categories>]
			[<filters>
				<filter [type="fieldId|fieldName"] target="Artist" operator="contains" value="love"/>
			</filters>]
			[<sortKeys>
				<sortKey [type="fieldId|fieldName"] target="Artist" order="asc|desc"/>
			</sortKeys>]
			[<properties>
				<property name="propname">value</property>
			</properties>]
		</query>]
		[<fields>
			<field id="101" />
			<field name="Title" />
		</fields>]
	</contents>
</mmRequest>

Request Notes

The element tag defines the element location where you want to see replacement songs. You can choose to replace an existing element, or insert an element before or after an existing element. The element tag has the following attributes:

 

  • airTime – indicates that starting time that the element aired or is scheduled to air. This is required for every request and is used to determine which hour the desired element is located in. You can narrow down the search for your target element and make a more exact match by using one or more of the additional optional properties that follow. Starting with MusicMaster PRO 5.0 SR-3, this is optional when you also specify a valid value in the historyId property. In that case the historyId value will be used to determine the hour containing the desired element.
  • historyId – the MusicMaster History ID of the element, if known. This can be obtained using and is the most exact way to target a specific element. If a valid History ID is specified, this will be used to determine which hour the desired element is located in. (Changed in MusicMaster PRO 5.0 SR-3)
  • Pos – indicates the relative position to the specified element for an add operation. You can replace the specified, or insert just before or after it. (before|after|replace)
  • songId – the MusicMaster Song ID of the element, if known.
  • cutId – the element ID from the third party system.

 

Note that while songId and cutId are both listed as optional, one or the other must be included. Performance can be improved by using the MusicMaster songId for this function.

 

  • testFilter – specifies the quality of replacement songs that may be returned. The value perfect means to only return songs that violate no rules. If there are no such songs, then none will be returned. Breakable means to only return only perfect songs and songs that violate breakable rules if necessary to reach the maxSongs count. If not specified, the default value is breakable.
  • maxSongs – the maximum number of best replacement songs that will be returned. Currently this has a maximum value of 99. If not specified, the default value is 10.
  • goalSort – indicates that you would like the song list that will be returned tested against the Optimum Scheduling Goals (if available). When this is specified, the song with the best goal score will be returned first and the worst will be last. To activate this function, add this tag with a value of 1. [Requires MusicMaster PRO 4.0 SR-20 or later]
  • query – You can optionally search the library for specific replacement songs using a query. The actual search request is provided in the contents/query section. All sections and tags are optional. You only need to include the portions necessary to define the desired search query. Using a query will override the list of categories that would normally be searched for the replacement songs. See Appendix B - Nexus Library Query Tags for complete details of the Nexus query tags.

When searching for replacement songs for an existing scheduled element, the default list will be all songs from the same song category as the one being replaced. When inserting a position, you should define at least the categories part of a query to indicate what songs to include in the search.



Creating a query that will test a very large list of potential songs can be very time consuming and should be avoided.

  • fields - The fields section must contain one field tag for each song field you wish to include in the reply message. You can use the id attribute with the internal field ID codes, or a name attribute with the user-specified field name. Only the specified fields will be returned for each song, in addition to song ID and, if defined, cut ID. You can obtain a list of available fields with the command. See Field Tag in Appendix C for addition options that can be used with your fields specification. This section is optional. If not specified, only the song ID and cut ID will be returned.

Sample Reply

<mmReply command="getReplacementSongs" station="Jill's Seminar Data" userData="hello" status="ok">
	<contents>
		<songList recordCount="3">
			<song songId="236">
				<field id="12" name="Run Time">03:25</field>
				<field id="102" name="Artist">NEIL DIAMOND and BARBRA STREISAND</field>
				<field id="134" name="Title">YOU DON'T BRING ME FLOWERS</field>
			</song>
			<song songId="449">
				<field id="12" name="Run Time">05:20</field>
				<field id="102" name="Artist">ABBA</field>
				<field id="134" name="Title">CHIQUITITA</field>
			</song>
			<song songId="251">
				<field id="12" name="Run Time">02:45</field>
				<field id="102" name="Artist">GORDON LIGHTFOOT</field>
				<field id="134" name="Title">IF YOU COULD READ MY MIND</field>
			</song>
		</songList>
	</contents>
</mmReply>

Reply Notes

The songid attribute of the SONG tag is the MusicMaster song ID number. A description including the primary and secondary fields is also included, as well as the song category. You can use the command to return additional song details if you wish. A custom list of return fields may be supported by this command in a future release. Currently, this command only returns the top X perfect songs in most to least rested order.

Common Usage

This command is most often used to note the changes made in the playlist. It is used in conjunction with other commands in a total sequence that looks for a new song (this command), removes the old song ) and adds the new song to the playlist. If the user deletes or skips an element, you would reconcile that change using ).

 

From the user's perspective this will look like a seamless process where they select the replacement song and see it added to the playlist.

Compatibility and Version Info

Available in all versions.

 

Starting with MusicMaster PRO 5.0sr3, the airTime property is no longer required when you have the history ID of the element you wish to change. It is recommended that you still specify an air time for compatibility with older versions. The history ID value will now take precedence over the specified airtime. [5001]